TREX not so complete cheatsheet
Plan
- svn Give a view of the TREX development branches and the external dependencies
- dir Give expected directory structure
- env Describe how to set your unix environment properly to compile/use TREX
- general Describe the configuration file used by TREX and/or AUV flight code and their relations
- run Show how to start a full mission on the vehicle or in simulation
SVN version and dependencies
The following picture illustrates the current svn tree with active and dead branches.
There are 3 active branches in TREX :
- the trunk which is the version we are now using on the AUV (since June 2010)
% svn co svn+ssh://kahuna.shore.mbari.org/svn/repos/TREX/trunk
- the multisim branch where the Monte-Carlo simulation is now connected to the auv-linux simulator
% svn co svn+ssh://kahuna.shore.mbari.org/svn/repos/TREX/branches/multisim
- the Europa_independent branch which is a full redesign of TREX in order to make it independent of Europa (allowing 3rd parties to integrate their own planner) and is also closer to the formal definition of the architecture (see AAMAS paper)
% svn co svn+ssh://kahuna.shore.mbari.org/svn/repos/TREX/branches/multisim
The two first branches rely on the same 3rd parties components and are fairly similar in the way they are compiled. The external tools needed are :
- jam (http://www.perforce.com/jam/jam.html) This is a make replacement utility used to compile TREX. The version used during development was jam 2.5
- boost (http://www.boost.org/) A set of libraries for advanced C++ programming. The version required is 1.36 and above.
- Europa 2.1.1 (http://babelfish.arc.nasa.gov/trac/europa) This is an old version of a planner development at NASA-Ames. The easiest way to have this version is to copy the full Europa directory from dorado1 account on threadfish :
% scp -r dorado1@threadfish:coding/Europa .
Europa have few extra dependencies that are given on this page
The Europa independent branch do not depend on Europa and will future the latest version of it in the future. It still depends on boost (1.40.0 or above) and jam
Directory structure
For compiling/executing correctly TREX expects the following directory structure
<path>
- auv-shared
- auv-linux
- auv (note: this is the auv-qnx directory and may be deprecated in the near future)
- Europa
- PLASMA
- TREX
We will assume on the rest of the document that this structure is respected.
 | Important requirement All TREX build system and execution assumes that important variables are defined. There's a file |
Mac specific : installing development tools
You need to have administration rights on this computer
on the Finder : select menu Go > Connect to Server ...
on the invite type : cifs://tornado.shore.mbari.org and <OK>
enter your login and password
select AppsAND <OK>
under the directory Macs/DevelopperTools/XcodeTools select the version of xcode for the OS version of your computer (10.6 = Snow Leopard) and get the xcode*.dmg file
you can then eject tornado disk
double click on the xcode*.dmg to mount the file
and then on Xcode.mpkg to start the installation
Building our old version of Europa/Plasma
To apply the patch and build Europa/Plasma with GCC 4.3:
% cd $PLASMA_HOME % patch -p1 < plasma-gcc4.3.patch #i.e. the attached patch file % jam && jam
Initializing TREX environment variables
The file <path>/TREX/devConfig should initialize the environment variable correctly for bash. To load it do the following :
% cd <path>/TREX (note: devConfig script need to be launched from this directory) % export HAS_AUV_LINUX=yes (note: do not define that if auv-linux is not compiled on your platform - e.g. Mac OS) % source devConfig % export VARIANTS=OPTIMIZED (note: to indicate to jam to compile in optimized mode ... so far debug mode is kind of
broken as Europa is too strong in some of its assert)
After that you should be able to compile the different component. If HAS_AUV_LINUX is set to yes make sure that auv-linux is correctly compiled and up to date. Then you need to compile Europa :
% cd $PLASMA_HOME % jam && jam (note: it is better to run it twice to make sure that the binary dependencies are taken care of)
To compile TREX libraries, first download the Boost C++ library (http://www.boost.org/) and install it following the instructions outlined in the site. Then compile TREX in a similar manner as Europa:
% cd $TREX_HOME % jam
after that you can compile the binaries amc and sim
% cd ctd2007 % jam amc % jam sim
amc is the batch command that execute the model without any terminal interaction. sim is a debug interface that can be used to step the agent execution using a limited set of commands through the terminal.
There's also a MonteCarlo sampler used for nightly build to exercise the model but we won't develop it here for now.
Finally, if you use the Monte-Carlo controller you need to compile batcher and samp
% cd ctd2007 % jam batcher samp
The trunk branch now assumes that batcher depends on samp so the compilation of samp is now done automatically. Still older versions (or other branches) did not enforce this dependency so it may be better to explicitly compile samp
Using TREX
TREX Configuration files :
On $TREX_HOME/ctd2007 you can find a bunch of .cfg files. They are used by TREX to confiugure itself for the mission a non exhaustive description follow :
- amc*.cfg: files defining the number and types of reactors used for the agent. By default the file used is amc.cfg (which is a copy of amc.sim.cfg) and its content on svn should not be modified (it may break the nightly builds). But locally you can replace the file by whichever correspond to your need. Description follow:
- amc.sim.cfg: self contained simulation. The VCS is simulated via a reactor exploiting the model given in simulator.nddl
- amc.vcs.cfg: connection to QNX. TREX connect to vcsServer and statePublisher remotely to execute the mission. Basic configuration for these connections is given by vcs.cfg
- amc.vcs.new.cfg: new implementation used for linux connection. This configuration will probably replace the amc.vcs.cfg in the near future. It also uses vcs.cfg to connect to the auv components.
- amc.play.cfg: used to replay a mission for debugging purpose.
- amc.vcs.dl.cfg: add an extra reactor that use CORBA to connect to an Iridum modem. This is used for mixed initiative. This current version is connecting to the modem driver from auv-linux while connecting to vcsServer and statPublisher from QNX. This connection to iridium modem allows TREX to send messages to the shore while possibly integrating new goals coming from there. For testing purpose we have also amc.sim.dl.cfg that allows to connect to this modem without needing a connection to other auv components.
- vcs.cfg: indicates the IP and port ussed for connecting to the vehicle. Its content should be :
<Config log="1" localPort="8002" remoteName="localhost" remotePort="8004" missionStart="init.cfg"> <Timeline name="vehicleState" command="0" /> <Timeline name="setpoint" class="Setpoint" command="1" /> <Timeline name="descend" class="Descend" command="1" /> <Timeline name="ascend" class="Ascend" command="1" /> <Timeline name="waypoint_yoyo" class="Waypoint" command="1" /> <Timeline name="getgps" class="GPS" command="1" /> <Timeline name="FireTheGulperAMC" class="Gulper" command="1" /> </Config>
remoteName should be the URL of the machine where the vcsServer is running. remotePort should have the same value as PORT in $AUV_CONFIG_DIR/vcsServer.cfg. localPort should have the same value as AMC_PORT in $AUV_CONFIG_DIR/statePublisher.cfg (check also in this file that AMC_IP points to the machine where TREX will run).
- init.cfg: is the initial plan sent to vcsServer check that the safety behaviors are consistent with the environment and TREX goals (e.g if the depth envelope is too shallow while TREX wants to do a yoyo with a high lower depth).
- Debug.cfg: used to activate/deactivate debug messages in $TREX_LOG_DIR/latest/Debug.log. by default it as the same content as Debug.Off.cfg you can replace it by Debug.On.cfg but be aware that TREX is very verbose in this case (implying a huge slow down) and it should not be used except when running sim binary which allows to unload/load this file on demand.
- *.solver.cfg: Europa configuration to tweak the plan solver for the given reactor.
- *.synch.cfg: Used to configure Europa during synchronization phase of TREX but it is deprecated now and will probably disappear as sson as I have checked that they are not used anymore.
other cfg files: These are the files defining the agent design for each missions. You will find normally correspondings *.exec.nddl *.skipper.nddl *.sim.nddl which describe the model instance for these missions (for example in science.x.skipper.nddl you will see the definition of a VolumeSurvey Goal).These configutrations files will be referred in the future as <mission>.cfg
Note on AUV configurations files useful for simulation :
all these files should be on $AUV_CONFIG_DIR
Make sure that latitude and longitude on workSite.cfg is close enough to the point where TREX expect to do the mission. Otherwise TREX will detect that it is too far from this point and simply do nothing.
Similarly on simulator.cfg check that the depths are reflecting what you would roughly expect at the place where the mission should be executed. These depths are provided by the config attributes depthn with n an integer.
Check statePublisher.cfg and vcssServer.cfg ass described on vcs.cfg item in previous section.
On QNX verify that devices.cfg starts the correct processes including statePublisher
On Linux check the *processes.cfg to see if it starts correct processes including statePublisher.
Note that threadfish.shore has a ready to go binary for AUV-Linux. Log in as 'dorado1' and cd down to 'coding/auv-linux'.
Starting a mission
Starting AUV code for TREX
This is required only if TREX expect a connection with the vehicle otherwise you can go directly to the next section.
% cd $AUV_HOME/altex/onboard/bin % ./vcsServer [-v] [-sim]
 | flags information
|
% omniNames& % notifd -c $OMNINOTIFY_HOME/channel.cfg& % cd $AUV_HOME/onboard/sampleConfig % ../bin/vcsServer -proc <proc>.cfg [-fastsim]
| flags information
|
Starting TREX in batch mode
% cd $TREX_HOME/ctd2007 % ./amc_o_rt <mission>.cfg [-fast|-sim] <nstep> Use <nstep> = 50
| Warning Currently argument position and order is fixed in TREX |
| flags information
|
You can see TREX activity by looking on $TREX_LOG_DIR/latest/TREX.log
% cd $TREX_LOG_DIR % tail -F latest/TREX.log
Starting TREX in interactive mode
% cd $TREX_HOME/ctd2007 % sim_o_rt <mission> [-sim] [<nstep>] Options: Q :- Quit N :- Next G :- Goto <tick> e.g. g100 R :- Reload Debug.cfg + :- enable pattern e.g. '+Agent' - :- disable pattern e.g. '-Agent' ! :- disable all debug messages >
You can see here that the command is quite similar to amc except that it exepect the name of the <mission> instead of <mission>.cfg.
You have then an interactive limited shell a la gdb where you can adnvance to a specific tick (g), step to next tick ( n ), etc commands R/+/-/! are used to manipulate how much data you want on the Debug.log starting from now.
| note about sim One can note that, as opposed to amc, sim does not have the flag -fast. It is due to the fact that by default sim uses the fast clock. |
